home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / PowerPlant / LBalloonTracker / LBalloonTracker.doc < prev    next >
Encoding:
Text File  |  1996-10-24  |  7.1 KB  |  133 lines  |  [TEXT/ttxt]
  1. LBalloonTracker - a class for implementing balloon help.
  2.  
  3.  
  4. What is it?
  5.  
  6. LBalloonTracker is a class that implements Balloon Help throughout an entire PowerPlant view hierarchy.  Typically used as a mix-in class with LWindow or LDialog, it displays help content corresponding to the pane under the pointer as well as the pane's state.  Help content is supplied in the form of a resource similar to the 'hdlg' resource, but with additional information in it.  This scheme minimises the number of points of intervention, i.e., the number of places where you have to add stuff to your code in order to implement Balloon Help.
  7.  
  8. The LBalloonTracker package contains these files:
  9.  
  10.     LBalloonTracker.doc  -- this documentation file
  11.     LBalloonTracker.cp   -- source file
  12.     LBalloonTracker.h    -- header file
  13.     LBalloonTracker.r    -- Rez template file for balloon help content
  14.     LBalloonTracker.tmpl -- Resorcerer template file for balloon help content
  15.  
  16.  
  17. How do I use it?
  18.  
  19. Unlike most other Balloon Help implementations for PowerPlant, LBalloonTracker is typically used as a mix-in class at the window level.  That is, programmers derive a new window class from both LBalloonTracker and either LWindow or LDialog.  Only a few functions need to be overridden.  Here's an example:
  20.  
  21. class MyWindow : public LWindow, public LBalloonTracker
  22. {
  23.     // other stuff here ...
  24.     
  25.     virtual void AdjustCursor(Point inPortPt, const EventRecord &inMacEvent);
  26.     virtual void HideSelf();
  27.     virtual void DeactivateSelf();
  28. };
  29.  
  30. void MyWindow::AdjustCursor(Point inPortPt, const EventRecord &inMacEvent)
  31. {
  32.     LWindow::AdjustCursor(inPortPt, inMacEvent);
  33.     TrackBalloons(this, inPortPt);
  34. }
  35.  
  36. void MyWindow::HideSelf()
  37. {
  38.     LWindow::HideSelf(inPortPt, inMacEvent);
  39.     RemoveBalloonsIfInTracker();
  40. }
  41.  
  42. void MyWindow::DeactivateSelf()
  43. {
  44.     LWindow::DeactivateSelf(inPortPt, inMacEvent);
  45.     RemoveBalloonsIfInTracker();
  46. }
  47.  
  48. The override of AdjustCursor is where control is transferred to the balloon tracking code (via the call to TrackBalloons).  The other two overrides ensure that any displayed balloons are removed when a window is hidden or becomes inactive.
  49.  
  50. In order to complete the picture, your window's creation code needs to tell the window which balloon help resource to look for.  You can do this easily:
  51.  
  52. void MyCreateWindow(LCommander* inSuperCommander)
  53. {
  54.     MyWindow* window;
  55.     
  56.     // create the window
  57.     window = (MyWindow *) LWindow::CreateWindow(1234, inSuperCommander);
  58.     // give it the ID of a balloon help resource
  59.     window->SetBalloonDataID(1234);
  60. }
  61.  
  62. You can also set the balloon help resource ID in the call to LBalloonTracker's constructor.  For example:
  63.  
  64. MyWindow::MyWindow(LStream* inStream)
  65.     : LWindow(inStream), LBalloonTracker(1234)
  66. {
  67. }
  68.  
  69.  
  70. How does it work?
  71.  
  72. LBalloonTracker, as its name implies, tracks the pointer across an entire view hierarchy.  Inside the call to TrackBalloons, it performs a depth-first search for panes that are underneath the cursor.  If it finds one, it extracts the pane's ID and uses it as a search key in the tracker's balloon help resource.  If balloon help is found for that pane, it is displayed;  if not, the tracker searches again using the pane's superview's ID.  This process is repeated until balloon help is found or we hit the top of the pane hierarchy.  If no help content is found, any currently displayed help balloon is removed.
  73.  
  74.  
  75. How do I define help content?
  76.  
  77. All of the balloon help resources described in Inside Macintosh ('hdlg', 'hwin', etc.) are index-based.  That is, they all assume that visual elements on the screen are identified linearly, in the way that Dialog Manager items are.  Unfortunately, this doesn't work very well with PowerPlant's hierarchical display system (how do you map an index onto a tree?).  For this reason, LBalloonTracker uses its own custom resource type for describing help content.  This resource, of type 'PPbl', is very similar to the Help Manager's 'hdlg' resource, except that every item in the resource consists of a key-value pair.  The key is a pane's ID, and the value is its help content.  For example:
  78.  
  79. #include "LBalloonTracker.r"
  80.  
  81. resource 'PPbl' (128, purgeable) {
  82.     kCurrentVersion, hmDefaultOptions, 0, 0, 
  83.     {
  84.         // pane #1
  85.         1000,     // pane ID
  86.         HMStringItem {
  87.             "this is help for the pane 1000's enabled state",
  88.             "this is help for the pane 1000's disabled state",
  89.             "this is help for the pane 1000's checked state",
  90.             "this is help for the pane 1000's other state"
  91.         },
  92.         
  93.         // pane #2
  94.         1001,     // pane ID
  95.         HMStringItem {
  96.             "this is help for the pane 1001's enabled state",
  97.             "this is help for the pane 1001's disabled state",
  98.             "this is help for the pane 1001's checked state",
  99.             "this is help for the pane 1001's other state"
  100.         },
  101.         
  102.         // etc.
  103.     }
  104. };
  105.  
  106. The help content can be specified in any of the ways defined by the 'hdlg' resource:  by embedded Pascal string (HMStringItem), by 'PICT' resource ID (HMPictItem), by 'STR#' resource ID and index (HMStringResItem), by 'TEXT' resource ID (HMTEResItem), and by 'STR ' resource ID (HMSTRResItem).
  107.  
  108. For each pane listed in the 'PPbl' resource, there are four possible help messages:  "enabled", "disabled", "checked", and "other".  These messages correspond to various states of the pane.  Note that LBalloonTracker will automatically detect state changes in panes, so the programmer doesn't have to do anything.
  109.  
  110. The possible pane states are determined as follows.  If the pane is disabled (as determined by a call to IsEnabled()), its state is "disabled".  If the pane is enabled and it does not derive from LControl, its state is "enabled".  If the pane is enabled and it does derive from LControl, we get the pane's value.  If the value is 0, the pane's state is "enabled";  if it's 1, the pane's state is "checked";  if it's anything else, the pane's state is "other".  This behaviour mimics the Help Manager's use of 'hdlg' resources.
  111.  
  112. Note:  In order to take advantage of the behaviour for LControls, the "Enable RTTI" option has to be turned on in the "C/C++ Language" panel of the Project Settings dialog.
  113.  
  114. There are two files that describe the format of LBalloonTracker's help resource:  "LBalloonTracker.r" contains a Rez type definition, and "LBalloonTracker.tmpl" contains a Resorcerer template.  There is no ResEdit template.
  115.  
  116.  
  117. Known problems
  118.  
  119. PowerPlant's use of LDefaultOutline and LFocusBox causes problems with the balloon-tracking mechanism.  This is because the outline and focus box aren't actually part of the panes they ostensibly enhance.  PowerPlant's own mouse-tracking functions (FindDeepSubPaneContaining) see the outline and focus box as being "on top of"  these panes.
  120.  
  121. I have no intention of "fixing" this, since in my own apps I use custom button & scroller classes that draw their own outline or focus box directly.
  122.  
  123.  
  124. Legal stuff
  125.  
  126. LBalloonTracker is © 1996 Corporate Software & Technologies Int. Inc. (CS&T).  Permission is granted for use of LBalloonTracker free of charge, other than acknowledgement of Paul Lalonde and CS&T in any program using LBalloonTracker (perhaps in an About box).
  127.  
  128.  
  129. Happy ballooning!
  130.  
  131. Paul Lalonde
  132. paull@cst.ca
  133.